Improve Optimization Detective documentation #1782
Draft
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
westonruter
added
[Plugin] Optimization Detective
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## trunk #1782 +/- ##
=======================================
Coverage 57.41% 57.41%
=======================================
Files 84 84
Lines 6521 6521
=======================================
Hits 3744 3744
Misses 2777 2777
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
… update/od-docs
westonruter
commented
Jan 23, 2025
Comment on lines
+201
to
+270
| * Once a page has finished rendering and the output buffer is processed, the page contents are loaded into | ||
| * an HTML Tag Processor instance. It then iterates over each tag in the document, and at each open tag it will | ||
| * invoke all registered tag visitors. A tag visitor is simply a callable (such as a regular function, closure, | ||
| * or even a class with an `__invoke` method defined). The tag visitor callback is invoked by passing an instance | ||
| * of the `OD_Tag_Visitor_Context` object which includes the following read-only properties: | ||
| * | ||
| * - `$processor` (`OD_HTML_Tag_Processor`): The processor with the cursor at the current tag. | ||
| * - `$url_metric_group_collection` (`OD_URL_Metric_Group_Collection`): The URL Metrics which may include information about the current tag to inform what optimizations the callback performs. | ||
| * - `$link_collection` (`OD_Link_Collection`): Collection of links which will be added to the `HEAD` when the page is served. This allows you to add preload links and preconnect links as needed. | ||
| * | ||
| * Note that you are free to call `next_tag()` in the callback (such as to walk over any child elements) since the | ||
| * cursor will be reset to the tag after the callback finishes. | ||
| * | ||
| * A tag visitor callback returns a boolean value. When it returns `true`, then Optimization Detective will mark the | ||
| * tag as needing to be included among the elements stored in URL Metrics. The element data includes properties such | ||
| * as intersectionRatio, intersectionRect, and boundingClientRect as well as whether it is the LCP element. If the | ||
| * current tag is not relevant for the tag visitor or if the tag visitor callback does not need to query the provided | ||
| * `OD_URL_Metric_Group_Collection` instance to apply the desired optimizations, it can just return `false`. An | ||
| * element will be tracked in URL Metrics if _any_ tag visitor callback returns `true` when visiting the tag. | ||
| * | ||
| * Here's an example tag visitor that depends on URL Metrics data: | ||
| * | ||
| * $tag_visitor_registry->register( | ||
| * 'lcp-img-fetchpriority-high', | ||
| * static function ( OD_Tag_Visitor_Context $context ): bool { | ||
| * if ( $context->processor->get_tag() !== 'IMG' ) { | ||
| * return false; // Tag is not relevant for this tag visitor. | ||
| * } | ||
| * | ||
| * // Make sure fetchpriority=high is added to LCP IMG elements. | ||
| * $common_lcp_element = $context->url_metric_group_collection->get_common_lcp_element(); | ||
| * if ( | ||
| * null !== $common_lcp_element | ||
| * && | ||
| * $common_lcp_element->get_xpath() === $context->processor->get_xpath() | ||
| * ) { | ||
| * $context->processor->set_attribute( 'fetchpriority', 'high' ); | ||
| * } | ||
| * | ||
| * // Must return true so that the tag is included among the elements stored in URL Metrics. | ||
| * return true; | ||
| * } | ||
| * ); | ||
| * | ||
| * Please note this implementation of setting `fetchpriority=high` on the LCP `IMG` element is simplified. Please | ||
| * see the Image Prioritizer extension for a more robust implementation. | ||
| * | ||
| * Here's an example tag visitor that does not depend on any URL Metrics data: | ||
| * | ||
| * $tag_visitor_registry->register( | ||
| * 'img-decoding-async', | ||
| * static function ( OD_Tag_Visitor_Context $context ): bool { | ||
| * if ( $context->processor->get_tag() !== 'IMG' ) { | ||
| * return false; // Tag is not relevant for this tag visitor. | ||
| * } | ||
| * | ||
| * // Set the decoding attribute if it is absent. | ||
| * if ( null === $context->processor->get_attribute( 'decoding' ) ) { | ||
| * $context->processor->set_attribute( 'decoding', 'async' ); | ||
| * } | ||
| * | ||
| * // There's no need to query OD_URL_Metric_Group_Collection, so this element | ||
| * // doesn't need to be tracked in URL Metrics and the callback can return false. | ||
| * return false; | ||
| * } | ||
| * ); | ||
| * | ||
| * Refer to [Image Prioritizer](https://github.com/WordPress/performance/tree/trunk/plugins/image-prioritizer) and | ||
| * [Embed Optimizer](https://github.com/WordPress/performance/tree/trunk/plugins/embed-optimizer) for additional | ||
| * examples of how tag visitors are used. |
There was a problem hiding this comment.
To be revisited with #1821
westonruter
modified the milestones:
optimization-detective 1.0.0-beta1,
optimization-detective n.e.x.t
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a follow-up to #1763.
@access privatefrom interfaces which are intended to be exposed.